Add HTTP proxy configuration documentation for WordPress core and WP-CLI #623

Copilot · 2026-02-03T00:30:29Z

Documents manual proxy configuration for both WordPress core HTTP requests and WP-CLI's own HTTP requests. WP-CLI doesn't honor HTTP_PROXY environment variable by default for security reasons.

Changes

Added "HTTP proxy configuration" section to references/config.md
Provides working examples using require config option to load proxy setup file
Example reads HTTP_PROXY env var and sets WordPress proxy constants (WP_PROXY_HOST, WP_PROXY_PORT, WP_PROXY_USERNAME, WP_PROXY_PASSWORD)
Includes validation for malformed URLs from parse_url()
Adds configuration for WP-CLI's own HTTP requests using http_request_args hook to configure the Requests library

Examples

WordPress core HTTP requests only

wp-cli.yml:

require:
  - proxy.php

proxy.php:

<?php
$proxy_env = getenv( 'HTTP_PROXY' );

if ( ! $proxy_env ) {
	return;
}

$proxy_url = parse_url( $proxy_env );

if ( ! is_array( $proxy_url ) || ! isset( $proxy_url['host'] ) ) {
	return;
}

define( 'WP_PROXY_HOST', $proxy_url['host'] );

if ( isset( $proxy_url['port'] ) ) {
	define( 'WP_PROXY_PORT', $proxy_url['port'] );
}

Both WordPress core and WP-CLI HTTP requests

proxy.php (extended):

<?php
$proxy_env = getenv( 'HTTP_PROXY' );

if ( ! $proxy_env ) {
	return;
}

$proxy_url = parse_url( $proxy_env );

if ( ! is_array( $proxy_url ) || ! isset( $proxy_url['host'] ) ) {
	return;
}

// Configure proxy for WordPress core HTTP requests
define( 'WP_PROXY_HOST', $proxy_url['host'] );

if ( isset( $proxy_url['port'] ) ) {
	define( 'WP_PROXY_PORT', $proxy_url['port'] );
}

// Configure proxy for WP-CLI's own HTTP requests
if ( class_exists( 'WP_CLI' ) ) {
	$add_proxy_to_request = function( $r, $url ) use ( $proxy_env ) {
		$r['proxy'] = $proxy_env;
		return $r;
	};
	
	WP_CLI::add_hook( 'http_request_args', $add_proxy_to_request );
}

Usage:

# WordPress core HTTP requests (plugin updates)
$ HTTP_PROXY=http://proxy.example.com:8080 wp plugin update --all

# WP-CLI HTTP requests (package installation)
$ HTTP_PROXY=http://proxy.example.com:8080 wp package install wp-cli/doctor-command

Original prompt

This section details on the original issue you should resolve

<issue_title>Add HTTP proxy configuration example</issue_title>
<issue_description>Split out from wp-cli/core-command#292

php-curl happens to honor the http_proxy env var

Requests defers honoring that env var to the library user (e.g., WordPress core or WP-CLI) (see also Auto use Proxy if HTTP_PROXY & HTTPS_PROXY Environment variable is set WordPress/Requests#218)

WP-CLI doesn't want to blindly trust that env var

One should be able to manually configure proxy support via wp-cli.yml and the extra-php config

You might be able to do something like this:
# In wp-cli.yml
require:
  - path-to/proxy.php
// proxy.php

$proxy_host = getenv( 'HTTP_PROXY' );

if ( ! $proxy_host ) {
	return;
}

$proxy_url = parse_url( $proxy_host );

if ( $proxy_url['host'] ) {
	define( 'WP_PROXY_HOST', $proxy_url['host'] );
}

if ( $proxy_url['port'] ) {
	define( 'WP_PROXY_PORT', $proxy_url['port'] );
}
This would configure the proxy for HTTP requests in core when using WP-CLI, similar to when you define this in wp-config.php. The setup would be slightly more complex for modifying HTTP requests from WP-CLI itself.</issue_description>

<agent_instructions>WP_Http_Proxy in WP core might serve as inspiration</agent_instructions>

Comments on the Issue (you are @copilot in this section)

Fixes Add HTTP proxy configuration example #601

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>

swissspidy · 2026-02-04T02:08:49Z

/gemini review

gemini-code-assist

Code Review

This pull request adds valuable documentation on configuring HTTP proxies for WP-CLI and WordPress core. The examples are clear and cover two important use cases. I've suggested a small improvement to the PHP examples to make them more robust by supporting HTTPS_PROXY and lowercase environment variables, which are common conventions.

gemini-code-assist · 2026-02-04T02:10:00Z

references/config.md

+ * uses for HTTP requests.
+ */
+
+$proxy_env = getenv( 'HTTP_PROXY' );


The current example only considers the HTTP_PROXY environment variable. It's a common practice to also support HTTPS_PROXY (for HTTPS requests) and lowercase variants (http_proxy, https_proxy).

Since WordPress Core doesn't differentiate between proxy settings for HTTP and HTTPS, it's best to prefer the HTTPS proxy variable if set, and fall back to the HTTP one. This makes the configuration more robust and aligns with user expectations.

Suggested change

$proxy_env = getenv( 'HTTP_PROXY' );

$proxy_env = getenv( 'HTTPS_PROXY' ) ?: getenv( 'https_proxy' ) ?: getenv( 'HTTP_PROXY' ) ?: getenv( 'http_proxy' );

gemini-code-assist · 2026-02-04T02:10:00Z

references/config.md

+ * Configure HTTP proxy for both WordPress core and WP-CLI HTTP requests.
+ */
+
+$proxy_env = getenv( 'HTTP_PROXY' );


The current example only considers the HTTP_PROXY environment variable. It's a common practice to also support HTTPS_PROXY (for HTTPS requests) and lowercase variants (http_proxy, https_proxy).

Since WordPress Core doesn't differentiate between proxy settings for HTTP and HTTPS, it's best to prefer the HTTPS proxy variable if set, and fall back to the HTTP one. This makes the configuration more robust and aligns with user expectations.

Suggested change

$proxy_env = getenv( 'HTTP_PROXY' );

$proxy_env = getenv( 'HTTPS_PROXY' ) ?: getenv( 'https_proxy' ) ?: getenv( 'HTTP_PROXY' ) ?: getenv( 'http_proxy' );

Initial plan

e822552

Copilot AI assigned Copilot and swissspidy Feb 3, 2026

Copilot started work on behalf of swissspidy February 3, 2026 00:30 View session

Copilot AI and others added 2 commits February 3, 2026 00:32

Add HTTP proxy configuration documentation

cc8900f

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>

Improve proxy configuration code robustness

5b9b82e

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add HTTP proxy configuration example~~ Add HTTP proxy configuration documentation Feb 3, 2026

Copilot AI requested a review from swissspidy February 3, 2026 00:34

Copilot finished work on behalf of swissspidy February 3, 2026 00:34

This comment was marked as resolved.

Sign in to view

Copilot started work on behalf of swissspidy February 3, 2026 01:28 View session

Copilot AI and others added 4 commits February 3, 2026 01:29

Add proxy configuration for WP-CLI's own HTTP requests

888bd90

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>

Remove trailing whitespace

7ec42c1

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>

Clarify unused parameter in hook callback

85fe0e2

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>

Add clarifying comments for proxy configuration

50e0150

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>

This comment was marked as resolved.

Sign in to view

Copilot AI changed the title ~~Add HTTP proxy configuration documentation~~ Add HTTP proxy configuration documentation for WordPress core and WP-CLI Feb 3, 2026

Copilot finished work on behalf of swissspidy February 3, 2026 01:32

gemini-code-assist bot reviewed Feb 4, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add HTTP proxy configuration documentation for WordPress core and WP-CLI #623

Add HTTP proxy configuration documentation for WordPress core and WP-CLI #623

Copilot AI commented Feb 3, 2026 •

edited

Loading

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

swissspidy commented Feb 4, 2026

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot Feb 4, 2026

Uh oh!

gemini-code-assist bot Feb 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	$proxy_env = getenv( 'HTTP_PROXY' );
	$proxy_env = getenv( 'HTTPS_PROXY' ) ?: getenv( 'https_proxy' ) ?: getenv( 'HTTP_PROXY' ) ?: getenv( 'http_proxy' );

Add HTTP proxy configuration documentation for WordPress core and WP-CLI #623

Are you sure you want to change the base?

Add HTTP proxy configuration documentation for WordPress core and WP-CLI #623

Conversation

Copilot AI commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Examples

WordPress core HTTP requests only

Both WordPress core and WP-CLI HTTP requests

Comments on the Issue (you are @copilot in this section)

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

swissspidy commented Feb 4, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Feb 3, 2026 •

edited

Loading